--- title: "Create payment" method: POST path: "/payments " --- # Create payment `POST /payments ` ## Headers - `Content-Type` string, required - `Host` string, required - `Date` string, required - `Digest` string, required - `Authorization` string, required - `Idempotency-Key` string - `x-satispay-deviceinfo` string - `x-satispay-devicetype` 'SMARTPHONE' | 'TABLET' | 'CASH REGISTER' | 'POS' | 'PC' | 'ECOMMERCE_PLUGIN' - `x-satispay-os` string - `x-satispay-osv` string - `x-satispay-apph` string - `x-satispay-appn` string - `x-satispay-appv` string - `x-satispay-tracking-code` string ## Request body - object - `flow` 'MATCH_CODE' | 'HOTP_AUTH' | 'MATCH_USER' | 'REFUND', required — The payment flows that you can use with Meal Vouchers are:

`MATCH_CODE` [DOC](https://developers.satispay.com/docs/one-off)
This flow can be used generically for one-off payments.

`HOTP_AUTH` [DOC](https://developers.satispay.com/docs/one-off-hotp)
This flow can be used to perform one-off payments via HOTP tokens.
To use this flow you must also include the `token` parameter.

`MATCH_USER` [DOC](https://developers.satispay.com/docs/payment-mobile-number)
This flow can be used for one-off payments on a specific user.
To use this flow you must also include the `consumer_uid` parameter.

`REFUND` [DOC](https://developers.satispay.com/reference/refund)
This flow can be used for refunds on a specific payment.
To use this flow you must also include the `parent_payment_uid` and the `amount_unit`. - `amount_unit` integer, required — The payment amount in cents.

For example, to represent the amount `€12.40`, you should multiply it by `100`, resulting in `1240` cents. - `currency` string, required — The payment currency.

Currently `EUR` is the only currency supported. - `payment_method_options` object - `meal_voucher` object — The veal vouchers settings object. - `enable` boolean — Enable or disable Meal Vouchers for this payment.

If you don't specify this parameter, and if your shop has Meal Vouchers enabled, by default it will be `true`. - `max_amount_unit` integer — The maximum amount payable with Meal Vouchers in cents.

This parameter is applicable when a customer purchases both food and non-food items. For instance, while the total grocery bill may amount to `€15.00`, the specific cost for food items might be of just `€6.50`.

To represent the amount `€6.50`, you should multiply it by `100`, resulting in `650` cents. - `max_number` integer — The maximum number of Meal Vouchers usable for this payment.

By default this parameter is set to `8`, in compliance with Italian law.

This parameter is applicable when a customer intends to make a payment using multiple meal voucher brands. For instance, the customer might use `3` Meal Vouchers from other brands and `5` Meal Vouchers from Satispay, resulting in a total of `8` Meal Vouchers. In the example above, the `max_number` parameter should be set to `5`, since `3` Meal Vouchers are from another brand. - `payment_options` object - `partial_payment` boolean — Enable or disable partial payments.

When partial payment is enabled, customers have the flexibility to pay a portion of the total amount using Meal Vouchers, without the need to use e-money funds from the Satispay wallet.
Customers can decide to use alternative payment methods to cover the remaining amount.

If this property is set to `true`, the `amount_unit` response property could change when the payment transitions to `ACCEPTED` status.
For example, the payment could be created at `12,40€`, but the consumer availability could just be of `8,00€` of Meal Vouchers.
In this case, the `amount_unit` response property will be of `800` cents corresponding in `8,00€`.

When partial payment is disabled, customers are required to pay the entire amount using Satispay, using a combination of both Meal Vouchers and e-money funds from their Satispay wallet.
In this case, if the customer has insufficient funds, the transaction will not be successful. - `token` string — The token required to charge the consumer wallet.
It can be an HOTP token.

Required with `HOTP_AUTH` flow only. - `consumer_uid` string — The unique id of the consumer required for payment acceptance.
To obtain the customer id, please use the [Get Consumer API](https://developers.satispay.com/reference/retrive-consumer).

Required with `MATCH_USER` flow only.

This parameter is deprecated; we suggest avoiding the `MATCH_USER` UX unless absolutely necessary. - `parent_payment_uid` string — The id of the payment that you want to refund.

Required with `REFUND` flow only. - `external_code` string — The external order id or payment identifier.

We highly recommend to use this field by populating it with your internal order id.
This string will be included in your reports for reconciliation and shown to the Satispay consumer in-app.

This field has a maximum length of 50 characters, including spaces. - `callback_url` string — The URL to be triggered via an HTTP GET request when there is a change in payment status.

When the given `callback_url` is invoked, a GET request for payment details can be made to retrieve the updated payment status.

Please note that `{uuid}` will be replaced with the generated payment id.
e.g. `https://example.com/satispay-callback?payment_id={uuid}`

You can read more [here](https://developers.satispay.com/reference/callback-s2s). - `redirect_url` string — This field specifies the URL where the user will be redirected after the payment flow from the Satispay app is completed.

For instance, you can set this URL to ensure users are redirected to that specific page upon successful payment completion.
e.g. `https://example.com/payment-redirect?order_id=your_order_id`

Please note that this field doesn't support any placeholder. - `metadata` object — The additional metadata for the payment.

This field supports up to 20 key-value pairs, with keys limited to 45 characters and values limited to 500 characters each. - `phone_number` string — This special metadata can be used to pre-fill the phone number field available if you're using a web-redirect flow.

The phone number must contain the prefix an shouldn't have any additional space.
e.g. `+393891122333` - `expiration_date` string — The UTC payment expiration datetime.

The format should be `ISO 8601` like this `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.

By default `MATCH_CODE` and `MATCH_USER` payments are valid for 2 hours.

This parameter cannot be used with `HOTP_AUTH` and `REFUND` flows. ## Response `200` OK - object - `id` string — The unique payment id.

This can be used for every eventual subsequent operations on the payment, including refunds. - `code_identifier` string — The Satispay code identifier.

This string can be encoded in a QR code that can be scanned by the user.
This property is only available in `MATCH_CODE` flow payments. - `type` string — The current payment type.

`TO_BUSINESS`
This type is used for payments from a consumer to a merchant.

`REFUND_TO_BUSINESS`
This type is used for payments from a merchant to a consumer (e.g. refunds). - `amount_unit` integer — The payment amount in cents.

For example, the amount `€12.40` is being represented as `1240` cents.

When using the parameter `payment_options.partial_payment` = `true`
this final amount could change when the payment will transition to `ACCEPTED` status. - `currency` 'EUR' — The payment currency. - `status` string — The current payment status.

`PENDING`
The payment is created and awaits user interaction, such as scanning the QR code.

`ACCEPTED`
The payment has been accepted and succesfully executed.
This status, during payment creation, is only available in Meal Voucher payments with the `HOTP_AUTH` flow. - `expired` boolean — The current payment expiration status.

It becomes `true` once it reaches the `expiration_date` without being accepted or canceled. - `metadata` object — The additional metadata for the payment. - `sender` object — The sender payment actor. - `id` string — The unique sender id.

This will only be available once the payment will be matched with a consumer. - `type` string — The sender type.

`CONSUMER`
This sender type is used when the payment goes from a consumer to a merchant.

`SHOP`
This sender type is used when the payment goes from a merchant to a consumer (e.g. refunds payments). - `name` string — The sender name.

This will only be available once the payment will be matched with a consumer. - `receiver` object — The receiver payment actor. - `id` string — The unique receiver id. - `type` string — The receiver type.

`CONSUMER`
This receiver type is used when the payment goes from a merchant to a consumer.

`SHOP`
This receiver type is used when the payment goes from a consumer to a merchant (e.g. refunds payments). - `insert_date` string — The UTC payment creation datetime. - `expire_date` string — The UTC payment expiration datetime.

This property can be ignored when using `PRE_AUTHORIZED` or `HOTP_AUTH` flows. - `description` string — The external_code set during the payment creation request.

Please use the `external_code` field instead. - `flow` string - `external_code` string — The `external_code` set during the creation request. - `redirect_url` string — The URL where to redirect the user to begin the Satispay payment flow.

This property is available only when the payment uses the `MATCH_CODE` flow. - `payment_method` object - `meal_voucher` object — The Meal Voucher payment part.

This property is available in payment creation only when:
- the payment uses the `HOTP_AUTH` flow.
- the payment contains Meal Vouchers in it. - `amount_unit` integer — The total amount of Meal Vouchers in this payment, in cents.

For example, the amount `€8.00` is being represented as `800` cents. - `number` integer — The total number of Meal Vouchers in this payment.

As per italian law, it can't be higher than `8` Meal Vouchers per payment. ## Other responses - `400` — 400 Bad Request - `401` — 401 Unauthorized - `403` — 403 Forbidden or invalid authorization header --- [API](https://skmtc.net/satispay/apis/satispay-gbusiness-api.md) · [All operations](https://skmtc.net/satispay/apis/satispay-gbusiness-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/satispay/satispay-gbusiness-api/versions/f91f20a37e6f/schema)